The Vibecoder's Guide to AI-trix

Introduction: Reversing the Docs to Code Ratio

Prompting is fragile. A long prompt gets edited, trimmed, and "improved" over time. After a few iterations, the agent drifts and no longer follows original constraints. AI-trix is a structured contract that separates system rules from instructions, ensuring quality, security, and operational durability.

This guide represents the structural spine of my portfolio projects. At each production concern, we point directly to the matching open-source repository as runnable, cloneable proof.

Part A: System Identity & Core Rules

A production-grade agent does not rely on soft prompts. It follows a strict identity rule set.

The Proof: Persistent recall is implemented in Agent-Recall (solution memory via token overlap) and failure memory is managed by Agent-Scars.

Part B: Agent Design Template

Every agent inside a multi-agent swarm must follow a strict input-process-output contract. Passing unstructured strings between agents invites system entropy.

The Proof: This modular anatomy of an agent is dissected and demonstrated in Agent-Anatomy.

Part C: Reality Files & Anti-Drift

When agents modify code, they drift from the documentation. Reality files act as a YAML-based ledger detailing exactly what is currently operational, experimental, or still stubbed.

The Proof: Using a separate constitution to audit agent outputs and detect drift against original rules is demonstrated in Agent-Constitution, while the runtime anti-drift prompt guarding is handled by Agent-Scars.

Part D: Scars & Incident Logging

When an agent makes a mistake, it must be recorded as a "scar." If the same error pattern is detected twice, a repeat guard block is immediately prepended to the system prompt to force self-correction.

The Proof: This pattern is fully implemented in Agent-Scars using a local SQLite instance with an automatic JSON fallback.

Part E: current-state.md

The `current-state.md` file is the master reference for human operators and AI agents alike. It tracks the current development phase, verified working features, partially completed stubs, and the top operational risks. It prevents agents from rebuilding working systems or claiming incomplete stubs as fully operational.

Part F: Security DNA Checklist

Multi-agent systems require rigorous security guardrails at the prompt and runtime level to prevent command injection and unauthorized data modification.

The Proof: These defense patterns, including prompt-injection filters, are described in Agentic Patterns and validated in Agent-Routing.

Part G: Observability

Every agent action must emit a structured event to a central stream. This allows the system to monitor token burn, API latency, and confidence distributions.

The Proof: This telemetry structure runs continuously inside the core loop of AgentKernel.

Part H: Fallback & Recovery

When API providers fail, the system must degrade gracefully without crashing. A recovery supervisor monitors stuck loops, restarts crashed agents, and routes calls down fallback provider chains.

The Proof: This cascade and the session circuit breaker logic are implemented in Agent-Routing.

Part I: Testing & Validation

Multi-agent templates require extensive unit and integration testing. Rather than relying on live LLM calls during testing, you must assert that:

• Input validation catches malformed types and prevents path traversals.
• JSON parsing functions recover gracefully from truncated markdown blocks.
• The budget circuit breaker trips instantly when simulated model call costs exceed constraints.
• The fallback model chain invokes local Ollama services when external networks are simulated as down.

Part J: Minimum Documentation Structure

A production-ready repository must possess a clear memory structure. We enforce a minimal directory template:

.claude/
├── CLAUDE.md                 ← System identity & core rules
├── ARCHITECTURE.md           ← Detailed system design
└── PATTERNS.md               ← Code implementation rules

memory/
├── current-state.md         ← Operator state ledger
├── scars.md                 ← Failure memory incidents
└── reality/
    └── llm-providers.yaml    ← Live API provider mapping

Part K: Customization Checklist

Before launching a new agent workspace using the AI-trix template, check off the configuration criteria:

• Assign a unique system name and namespace to prevent state namespace collisions.
• Set the hard budget limits (e.g. maximum $2.00 per execution loop).
• Establish fallback providers and ensure local Ollama has download routes for offline execution models.
• Populate initial subsystem configurations in `memory/reality/` to initialize the reality-first truth engine.